/**
 * $version:  0.1 
 * $Date: 2011-01-21 
 *
 * Copyright (C) 2010-2011 Jawa Software. All rights reserved.
 *
 */

package org.jawa.learning.service;

import java.util.List;

import org.jawa.core.exception.AlreadyExistsException;
import org.jawa.core.exception.NotFoundException;
import org.jawa.core.exception.UserNotFoundException;
import org.jawa.learning.dao.UserDao;
import org.jawa.learning.model.User;
import org.jawa.learning.webapp.util.Page;

/**
 * 用户管理，包括加载、查询、创建、删除以及修改.
 * 
 * @see User
 */
public interface UserManager extends GenericManager<User, Long> {

	/**
	 * Convenience method for testing - allows you to mock the DAO and set it on
	 * an interface.
	 * 
	 * @param userDao
	 *            the UserDao implementation to use
	 */
	void setUserDao(UserDao userDao);

	/**
	 * Retrieves a user by userId. An exception is thrown if user not found
	 * 
	 * @param userId
	 *            the identifier for the user
	 * @return User
	 */
	User getUser(String userId);

	/**
	 * Finds a user by their username.
	 * 
	 * @param username
	 *            the user's username used to login
	 * @return User a populated user object
	 * @throws NotFoundException
	 * @throws org.springframework.security.core.userdetails.UsernameNotFoundException
	 *             exception thrown when user not found
	 */
	User getUserByUsername(String username) throws UserNotFoundException;

	/**
	 * Retrieves a list of all users.
	 * 
	 * @return List
	 */
	List<User> getUsers();

	/**
	 * Retrieves a list of all users.
	 * 
	 * @return List
	 */
	Page<User> getUsers(User user, Page<User> page);

	/**
	 * Saves a user's information.
	 * 
	 * @param user
	 *            the user's information
	 * @throws UserExistsException
	 *             thrown when user already exists
	 * @return user the updated user object
	 */
	User saveUser(User user) throws AlreadyExistsException;

	/**
	 * Update user`s information.
	 * 
	 * @param user
	 * @return
	 * @throws Exception 
	 */
	User updateUser(User user) throws Exception;

	/**
	 * Removes a user from the database by their userId
	 * 
	 * @param userId
	 *            the user's id
	 */
	void removeUser(String userId);

}